QuickTime - The Beta Release

home *** CD-ROM | disk | FTP | other *** search

/ QuickTime - The Beta Release / QuickTime - The Beta Release.iso / Programming Stuff / Beta Read Me

Wrap

Text File | 1991-09-06 | 54KB | 1,315 lines

This README file details the changes to QuickTime™ since the Alpha CD. Changes are detailed in the following manner. There is a brief statement of the change. This is followed by the routines that were changed, added, or removed. Then there is a discussion of what the change means to your application. GESTALT The version number returned by Gestalt for QuickTime is the full version specification ( version # byte, 2nd/3rd parts of version #, development/alpha/beta/release, stage of prerelease version ). The version number returned by the image compression manager and the component manager are interface compatability versions of the form long = version #. (ImageCompression version is 15, Component Manager version is 1) M O V I E S T O O L B O X MISC NAME CHANGES The names of a few constants and field names changed... struct SoundDescription { /* NEW OLD */ long descSize; long size; long dataFormat; long type; long resvd1; long resvd2; short version; short revlevel; long vendor; short numChannels; short sampleSize; short compressionID; short packetSize; Fixed sampleRate; }; ---------- NEW CONSTANT NAME OLD CONSTANT NAME usageTrackInMovie trackUsageInMovie usageTrackInPreview trackUsageInPreview usageTrackInPoster trackUsageInPoster cmfDeleteCurFile createMovieFileDeleteCurFile cmfDontCreateMovie createMovieFileDontCreateMovie cmfDontOpenMovieFile createMovieFileDontOpenMovieFile MOVIE TIMEBASES New routines for working with a movie's timebase. ---------- ADDED: pascal void SetMovieMasterTimeBase( Movie m, TimeBase tb, const TimeRecord *slaveZero); ADDED: pascal void SetMovieMasterClock( Movie m, Component clockMeister, const TimeRecord *slaveZero ); ---------- These calls are the same as their TimeBase.h counterparts, except that they work with the Movie's timebase. There is extra bookkeeping that must be performed when changing a movie's timebase in these ways (callbacks cancelled, etc). You shouldn't call SetTimeBaseMasterTimeBase or SetTimeBaseMasterClock on a movie's timebase, instead, use these calls. Since Callbacks are dependent on the MasterClock, changing the MasterClock or MasterTimeBase of a TimeBase with CallBacks can be deadly. Not for the weak of heart. TIMERECORD CompTimeValue has been renamed to Int64. There is no change in field meaning or location. Note, an Int64 is now typedef'ed as a struct rather than an array for easier field access. ---------- OLD: CompTimeValue long[2]; NEW: struct Int64 { long hi; long lo; }; ---------- The value field of the TimeRecord, which was previously a CompTimeValue, is now an Int64. ---------- OLD: struct TimeRecord { CompTimeValue value; TimeScale scale; TimeBase base; }; NEW: struct TimeRecord { Int64 value; TimeScale scale; TimeBase base; }; ---------- VIDEO MEDIA GRAPHICS MODE Parameter change to Get/SetVideoMediaGraphicsMode ---------- OLD: pascal HandlerError GetVideoMediaGraphicsMode( MediaHandler mh, long *graphicsMode, long *opColor ) NEW: pascal HandlerError GetVideoMediaGraphicsMode( MediaHandler mh, long *graphicsMode, RGBColor *opColor ) ^^^^^^^^ ---------- OLD: pascal HandlerError SetVideoMediaGraphicsMode( MediaHandler mh, long graphicsMode, long opColor ) NEW: pascal HandlerError SetVideoMediaGraphicsMode( MediaHandler mh, long graphicsMode, const RGBColor *opColor ) ^^^^^^^^^^^^^^^^ ---------- When getting or setting the VideoMediaGraphicsMode, you must pass an RGBColor for the opColor. SOUND MEDIA GRAPHICS MODE The Get/SetSoundMediaBalance calls allow you to set and store values for balance, BUT they have no effect on sound playback at this time. DISPLAY BOUNDS Calls were added to get the display bounds of a movie or track over a period of time. ---------- ADDED: pascal RgnHandle GetMovieSegmentDisplayBoundsRgn( Movie m, TimeValue time, TimeValue duration ); ADDED: pascal RgnHandle GetTrackSegmentMovieDisplayBoundsRgn( Track t, TimeValue time, TimeValue duration ); ---------- GONE: pascal void GetMovieDimensions( Movie m, Fixed *width, Fixed *height ); ---------- Since the movie and track display bounds calls return the display bounds of the movie or track at the current movie time, it was impossible to get the display bounds of a movie or track over the whole movie or portion of the movie. With GetMovieSegmentDisplayBoundsRgn and GetTrackSegmentMovieDisplayBoundsRgn, you can now get this information. Both return a bounds rgn in the display coordinate system. GetMovieDimensions was removed. This information can be obtained by either calling GetMovieBox or the full region being occupied can be gotten by calling GetMovieDisplayBoundsRgn or GetMovieSegmentDisplayBoundsRgn. LOADTRACKINTORAM LoadTrackIntoRam was added to complement LoadMovieIntoRam and LoadMediaIntoRam. ---------- ADDED: pascal OSErr LoadTrackIntoRam(Track t, TimeValue when, TimeValue duration, long flags) ---------- LoadTrackIntoRam loads a portion of the track into ram. STATUS ROUTINES Status routines were added so you can determine if a track is having trouble performing its duties during MoviesTask. ---------- ADDED: pascal ComponentResult GetTrackStatus(Track t); ADDED: pascal ComponentResult GetMovieStatus(Movie m, Track *firstProblemTrack); ---------- GetTrackStatus returns the error code which is the last error the media encountered during playback. It can only be cleared by the media when it believes the situation that caused the error has gone away. GetMovieStatus scans all active tracks of a movie and returns the error from the first problem track along with the track itself. MOVIE POSTERS: Calls were added to deal with the display bounds of a poster. ---------- ADDED: pascal void GetPosterBox( Movie m, Rect *boxRect ); ADDED: pascal void SetPosterBox( Movie m, const Rect *boxRect ); ---------- Previously, it was close to impossible to get the bounds of the poster. Since there is no "Poster Mode", you could not get this spatial information from the movie spatial routines. A movie file’s Poster is no longer automatically shown in Standard File. Instead, the Movie Preview component may be called to give the file a PICT thumbnail which is based on the movie’s poster frame. In future versions of QuickTime, the movie preview component may also add motion previews to a movie file. You may give a movie file a preview thumbnail that is unrelated to the poster frame by calling the PICT Preview component to add a thumbnail that your application creates. Read about preview components later in this document. MOVIE PREVIEWS GetMoviePreviewPict was removed. ---------- GONE: pascal PicHandle GetMoviePreviewPict ( Movie m, TimeValue time ); ---------- If you want a pict for the preview, use SetMoviePreviewMode to go into preview mode and use GetMoviePict to make a pict. If you want to preserve the mode prior to getting the pict, bracket the above calls with GetMoviePreviewMode and SetMoviePreviewMode. A movie’s preview is never used for previewing a movie file in Standard File. The “preview” settings supported by the Movies Toolbox may be used for application-specific needs. Read about preview components later in this document. COVER PROCS CoverProcs were added to give the application full control over what gets displayed when a spatial track "goes away". When time is in an empty portion of a track or past the duration of a track, the display area that the track used to occupy must be erased. CoverProcs allow extra control for applications. ---------- ADDED: pascal void SetMovieCoverProcs(Movie m, MovieRgnCoverProc uncoverProc, MovieRgnCoverProc coverProc, long refcon); ADDED: typedef pascal OSErr (*MovieRgnCoverProc)(Movie m, RgnHandle changedRgn, long refcon); ---------- If no CoverProc is set (the default case), the display area uncovered by a track is erased using the backColor, foreColor, and background pattern or pixpat, of the gworld when the movie's GWorld was set. A movie's GWorld is implicitly set by a NewMovie… call or explicitly set with SetMovieGWorld. When you call SetMovieGWorld explicitly or implicitly (by creating a new movie), the movie toolbox remembers the current foreground and background colors in the port along with the background pattern or pixpat. By default, it uses this information to erase any areas uncovered by tracks going away. You may instead install a movie uncover proc to do the erasing (or nothing if you like). You may also install a cover proc that is notified when the movie newly covers over a region. This would be useful if you are actively drawing something behind the movie. Your cover proc should return an error value. If no error occured, return 0. ACTIVE MOVIE SEGMENT Calls were added to set and get the current active movie segment. ---------- ADDED: pascal void SetMovieActiveSegment(Movie m, TimeValue startTime, TimeValue duration); ADDED: pascal void GetMovieActiveSegment(Movie m, TimeValue *startTime, TimeValue *duration); ---------- The active movie segment is that portion of the movie that is to be played. No samples outside of this range will be displayed/played when MoviesTask is called. This is very useful for playing sections of a movie. The active movie segment is not part of the information saved with a movie. All times are in the movie's TimeScale. To set the active movie segment to the entire movie, use a start time of -1. In this case, the duration is ignored. The default active movie segment is the entire movie. Attempting to set movie time to a value outside of the active segment range will result in the time passed being pinned to the start or stop time of the active segment. Several other calls are affected by the active movie segment. They include GotoBeginningOfMovie - goes to the beginning of the active segment of the movie GotoEndOfMovie - goes to the end of the active segment of the movie. IsMovieDone - bases its result on the active segment. TrackTimeToMediaTime - returns -1 if Track time is outside of active movie segment. Calling SetMoviePreviewMode(m,true) causes the active segment to be set to the segment of the movie containing the preview. Calling SetMoviePreviewMode(m,false) causes the active segment to be reset to the entire movie. PlayMoviePreview saves and restores the active segment for you. The next interesting time calls are also affected. They now respect the active segment by default. This means that any next interesting time call will not return values outside of the range of the active segment. You can override this by setting the "nextTimeIgnoreActiveSegment" bit in the flags field of the interesting time calls. DISPOSE TRACK MEDIA For the sake of consistancy, RemoveTrackMedia is now DisposeTrackMedia ---------- OLD: pascal void RemoveTrackMedia( Media m ) NEW: pascal void DisposeTrackMedia( Media m ) ^^^^^^^ ---------- INSTANTIATING MOVIES FROM HANDLES NewMovieFromResHandle and NewMoviePublicMovie are consolidated into NewMovieFromHandle. MakePublicMovie changed its name to PutMovieIntoHandle; ---------- OLD: pascal OSErr NewMovieFromResHandle( Movie *m, Handle publicMovie, short flags, Boolean *dataRefWasChanged ) NEW: pascal OSErr NewMovieFromHandle( Movie *m, Handle freezeDriedMovie, ^^^^^^^^^^^^^^^^^^ short flags, Boolean *dataRefWasChanged ) ---------- GONE: pascal Movie NewMoviePublicMovie( Handle publicMovie, long flags, Boolean *dataRefWasChanged ); ---------- OLD: pascal OSErr MakePublicMovie( Movie m, Handle publicMovie ) NEW: pascal OSErr PutMovieIntoHandle( Movie m, Handle freezeDriedMovie ) ^^^^^^^^^^^^^^^^^^ ---------- NewMovieFromHandle is used regardless of whether the handle is a resource or not. If it is a resource, we do some extra work to make sure that DataRefs are properly maintained. If you get the movie from a resource, you should not detach it. If you detach it, we won't know what file it came from and we can't do all that nice DataRef self-referenced bookkeeping for you. The handle based routines are now NewMovieFromHandle and PutMovieIntoHandle. DEALING WITH THE SCRAP Routines were added to assist in dealing with the scrap. ---------- ADDED: pascal OSErr PutMovieOnScrap(Movie m, long someMoreFlags); ADDED: pascal Movie NewMovieFromScrap(long newMovieFlags); ---------- Use PutMovieOnScrap when you put a movie onto the scrap. The MoviesToolbox will automatically put the suggested resources onto the scrap (PICT as well as the movie). By using this routine, if there are other standard resources which should be put onto the scrap, it will happen automatically. PutMovieOnScrap takes a long of flags. Two flags are currently defined as shown below enum { movieScrapDontZeroScrap = 1<<0, movieScrapOnlyPutMovie = 1<<1 }; If you set "movieScrapDontZeroScrap", PutMovieOnScrap will NOT call ZeroScrap before putting the movie on the scrap. This is useful when you want to put data on the scrap before the movie. If you set "movieScrapOnlyPutMovie", PutMovieOnScrap will only put movie data onto the scrap. If this flag is not set, PutMovieOnScrap may put other kinds of data on the scrap as well, such as a Picture. The two flags to PutMovieOnScrap may be combined. NewMovieFromScrap will create a movie from the scrap. The flags are the same as you would pass to NewMovieFromFile or NewMovieFromHandle. MOVIE PROGRESS PROCS MovieProgressProcs now take a refcon and a message parameter. ---------- OLD: pascal void SetMovieProgressProc(Movie m, MovieProgressProcPtr p); NEW: pascal void SetMovieProgressProc(Movie m, MovieProgressProcPtr p, long refcon); ^^^^^^^^^^^ ---------- OLD: typedef pascal Boolean (*MovieProgressProcPtr)(Movie m, short whatOperation, Fixed percentDone); NEW: typedef pascal Boolean (*MovieProgressProcPtr)(Movie m, short message, short whatOperation, Fixed percentDone, long refcon); ^^^^^^^^^^^^^ ^^^^^^^^^^^ ---------- GONE: pascal MovieProgressProcPtr GetMovieProgressProc(Movie m); ---------- The movie progress procs have changed in two ways. GetMovieProgressProc is gone, your app will have to remember what you set the movie progress proc to. Second, the progress proc routines now take two new parameters, refcon and message. The refcon is available for your use and is set in the SetMovieProgressProc routine. The message is one of the three following constants: enum { movieProgressOpen = 0, movieProgressUpdatePercent = 1, movieProgressClose = 2 }; The first time your progress proc is called for a given opeation, the message "movieProgressOpen" is sent. After that you will get one or more "movieProgressUpdatePercent" messages, and finally a "movieProgressClose" when the operation is complete. Constants have been defined for "whatOperation". They are as follows (the calls that could invoke them are shown after the constant): enum { progressOpFlatten = 1, FlattenMovie/FlattenMovieData progressOpInsertTrackSegment, InsertTrackSegment progressOpInsertMovieSegment, InsertMovieSegment progressOpPaste, PastMovieSelection progressOpAddMovieSelection, AddMovieSelection progressOpCopy, CopyMovieSelection (progress not yet implememented) progressOpCut CutMovieSelection (progress not yet implememented) }; The percentDone field is only meaningful with the "movieProgressUpdatePercent" message. The return value is only looked at for the "movieProgressUpdatePercent" message. NO TRACK TIMESCALES Tracks no longer have their own track timescale (time coordinate system) or timebase. Tracks use the movie's timescale. ---------- OLD: pascal Track NewMovieTrack( Movie m, TimeValue movieTimeOffset, TimeScale timeScale, Fixed width, Fixed height ); ------------------- NEW: pascal Track NewMovieTrack( Movie m, Fixed width, Fixed height, short trackVolume); ^^^^^^^^^^^^^^^^^ ---------- OLD: pascal Movie NewMovie( long flags, TimeScale timeScale ) ------------------- NEW: pascal Movie NewMovie( long flags ); ---------- GONE: pascal TimeScale GetTrackTimeScale( Track t ) GONE: pascal void SetTrackTimeScale( Track t, TimeScale timeScale ) GONE: pascal TimeBase GetTrackTimeBase( Track t ); GONE: pascal TimeValue GetTrackTime( Track t, TimeRecord *currentTime ); GONE: pascal TimeValue GetMediaTime( Media m, TimeRecord *currentTime ); ---------- Since tracks no longer have their own timescale, the timescale parameter was removed from NewMovieTrack. We also provide a resonable default timeScale when a movie is created with NewMovie. You can always change it by calling SetMovieTimeScale. The trackVolume parameter for NewMovieTrack should be zero for tracks without sound. A track's purpose in life is to map movie time to media time. Tracks having their own independent timescale did not make much sense. Tracks now use the Movie's timescale when defining edits. This eliminated a major problem encountered during editing. If tracks had a timescale different from the movie, it could be impossible to seam tracks temporally. A track could easily not end on an integral movie timevalue, but tracks could only begin on integral movie timevalues. This made it impossible to reliably seam tracks in time (track B could not begin exactly when track A ended). Since most of you were creating tracks with the same timescale of the media, you will have to review your calls to InsertTrackMedia, which has been renamed InsertMediaIntoTrack. Track durations are no longer just the media duration. Since tracks do not have their own time coordinate system, there is no longer a movie offset for each track. Each track starts at time zero. BUT, we have maintained the concept of a movie offset for a track. You can still get and set the movie offset for a track. An offset translates into the track starting with an empty segment. If the track does not start with an empty segment, the track has no movie offset (=zero). Therefore, the movie offset is the duration of this empty segment. BUT, a track's duration includes this empty segment. Therefore, the duration of the active segment of a track is the track's duration minus its track offset/first empty segment. INSERTTRACKMEDIA InsertTrackMedia changed its parameters and became InsertMediaIntoTrack. ---------- OLD: pascal OSErr InsertTrackMedia( Track trackH, TimeValue trackStart, TimeValue trackDuration, ----------------------- TimeValue mediaStartTime, TimeValue mediaDuration); NEW: pascal OSErr InsertMediaIntoTrack( Track trackH, TimeValue trackStart, TimeValue mediaStartTime, TimeValue mediaDuration, Fixed mediaRate ); ^^^^^^^^^^^^^^^ ---------- You don't have to calculate the track duration of the media you are adding anymore. Instead you tell us the rate to play the media. In addition, trackStart == -1 tells us to add to the end of the track. DATAREFS DataRefs have changed dramatically since the Alpha CD. First of all, we allow for media with multiple DataRefs (eg. a PICT media handler needs a data ref for every file it references). Second, we try to be smarter about default data refs so that most applications do not have to worry about DataRef's at all. Let's deal with the high-level routines which should make your life easier. ---------- OLD: pascal OSErr OpenMovieFile( const FSSpec *fileSpec, short *resRefNum, char perms, MoviesDataRef *dataRefH ); ----------------------- NEW: pascal OSErr OpenMovieFile( const FSSpec *fileSpec, short *resRefNum, char perms); ---------- OLD: pascal OSErr CreateMovieFile( const FSSpec *fileSpec, OSType creator, ScriptCode scriptTag, short flags ); NEW: pascal OSErr CreateMovieFile( const FSSpec *fileSpec, OSType creator, ScriptCode scriptTag, long flags, short *resRefNum, Movie *newmovie ); ^^^^ ^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ---------- OLD: pascal Media NewTrackMedia( Track t, long mediaType, MoviesDataRef mediaDataRef, TimeScale timeScale) -------------------------- NEW: pascal Media NewTrackMedia( Track t, OSType mediaType, ^^^^^^ TimeScale timeScale, Handle dataRef, OSType blobType ); ^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ---------- ADDED: pascal OSErr DeleteMovieFile( const FSSpec *fileSpec ); ADDED: pascal OSErr RemoveMovieResource( short resRefNum, short resId ); ---------- The basic assumption is that when media is added to a movie, the data wants to be in the same file as the movie resource. Keeping this in mind, when you instantiate a movie using NewMovieFromHandle, we know what file it came from if the handle is a resource. Because of this, OpenMovieFile no longer returns a DataRef that you HAD to keep around when calling NewTrackMedia. To handle the case in creation, we give you the ability to get a new movie back from CreateMovieFile (and this gives us a chance to remember the file the movie came from). The flags to CreateMovieFile now have creation related flags and new movie related flags (see the interface files for these flags). You may also specify whether to return the refnum of the resource file for the movie (this is the resRefNum to pass to AddMovieResource). NewTrackMedia takes the new form of data refs. If nil is passed for the dataRef, the dataRef the ToolBox remembers from CreateMovieFile or NewMovieFromHandle is used. Therefore, in the normal case, just pass nil for the dataRef to NewTrackMedia. DeleteMovieFile and RemoveMovieResource are used when expunging a movie file or movie resource. We do some extra bookkeeping about what files are used by what movies, so use these calls instead of FSpDelete and RmveResource. If you don't, there will be extra resources left around in your data files and your movie file. Now we can go into the new form of data refs. Data refs are blobs of data (Handles) that tell a media where to get the data from. A data ref consists of the blob of data, the blob type (what type of information is in the blob), and blob attributes. The current media handlers only use data refs which are Aliases. Therefore, to create a data ref today, just use NewAlias or NewAliasMinimal. The type is 'alis'. The only attribute currently in use is Self-referenced (which means the data is in the same file as the movie resource). In addition, a media may now refer to more than one data ref. Therefore, data refs are refered to by index. The architecture provides for multiple data refs, but the current implementations of the media only support one data ref. ---------- GONE: pascal MoviesDataRef NewDataRef( AliasHandle alias ); GONE: pascal void DisposeDataRef(MoviesDataRef dataRef); GONE: pascal MoviesDataRef MakeMoviesDataRef(const FSSpec *theFile); GONE: pascal Boolean GetDataRefSelfReferenced( MoviesDataRef dataRef ); GONE: pascal void SetDataRefSelfReferenced( MoviesDataRef dataRef, Boolean isSelfReferenced ); GONE: pascal void SetDataRefAlias( MoviesDataRef dataRef, AliasHandle alias ); GONE: pascal OSErr ResolveDataRef( MoviesDataRef dataRef, long flags, Boolean *dataRefWasChanged ); GONE: pascal AliasHandle MakeAliasFromDataRef( MoviesDataRef dataRef ); ---------- The above calls are no longer needed. Since data refs are just handles, we don't need special constructor or destructor methods. Since 'alis' data refs are just aliases, you can use the alias manager to make the data ref blobs and resolve them. Since self-referenced is now a bit in a data ref's attributes, we don't need special calls just for self-referenced information. ---------- ADDED: pascal OSErr GetMediaDataRefCount( Media media, short *count ); ---------- OLD: pascal MoviesDataRef GetMediaDataRef( Media m ) NEW: pascal OSErr GetMediaDataRef( Media media, short index, ^^^^^ ^^^^^^^^^^^ Handle *blob, OSType *blobType, long *attributes ); ^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^ ---------- OLD: pascal OSErr SetMediaDataRef( Media m, MoviesDataRef dataRef ) NEW: pascal OSErr AddMediaDataRef( Media m, short *index, Handle blob, OSType blobType ); ^^^ ^^^^^^^^^^^^ ^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ---------- Since media can have multiple data refs, you must request them by index. GetMediaDataRefCount returns the number of data refs a media has. GetMediaDataRef now returns the blob, blobType, and blobAttributes of a dataref. You may set any of these handles to nil if you do not want the information. For example, you may just want to look at the attributes or types without actually reading in the data. SetMediaDataRef changed to AddMediaDataRef. Once a media needs a DataRef, it will always need it. Therefore, you can only add DataRefs. ---------- OLD: pascal void GetMediaDataHandlerDescription( Media m, long *type, Str255 *creatorName, long *creatorManufacturer ) NEW: pascal void GetMediaDataHandlerDescription( Media m, short index, OSType *type, Str255 creatorName, OSType *creatorManufacturer ) ^^^^^^^^^^^ ^^^^^^ ^^^^^^ ---------- OLD: pascal DataHandler GetMediaDataHandler( Media m ) NEW: pascal DataHandler GetMediaDataHandler( Media m, short index ) ^^^^^^^^^^^ ---------- OLD: pascal OSErr SetMediaDataHandler( Media m, DataHandler dataHandler ) NEW: pascal OSErr SetMediaDataHandler( Media m, short index, DataHandler dataHandler ) ^^^^^^^^^^^ ---------- For every DataRef, a media needs a DataHandler for it. Therefore, you must access the data handlers of a media by index as well. The number of DataHandlers is the same as the number of DataRefs, so use GetMediaDataRefCount to determine the maximum index for DataHandlers. NEXT INTERESTING TIME There was a trivial change made to the interface for GetMovieNextInterestingTime. What is more interesting is that the next interesting time flags are more interesting and the interesting definitions follow. ---------- OLD: pascal void GetMovieNextInterestingTime( Movie m, short flags, short numMediaTypes, long *whichMediaTypes, TimeValue time, Fixed rate, TimeValue *interestingTime, TimeValue *interestingDuration ); NEW: pascal void GetMovieNextInterestingTime( Movie m, short flags, short numMediaTypes, const OSType *whichMediaTypes, ^^^^^^^^^^^^ TimeValue time, Fixed rate, TimeValue *interestingTime, TimeValue *interestingDuration ); ---------- While we are talking about next interesting time calls, let's discuss what all those different flags mean. nextTimeMediaSample - returns time of the next media sample (not very useful for sound media) nextTimeMediaEdit - returns time that the sample description changes (eg. when the compression type changes for Image Compression - 'RLE ' to 'RAW ') nextTimeTrackEdit - returns time of the next track edit. The end of the track is considered an edit. nextTimeSyncSample - returns time of the next self-contained sample (key frame for video) nextTimeEdgeOK - if the thing you are looking for (sample, mediaEdit, trackEdit, or SyncSample) at the "time" you pass in, that time can be returned. An example is when you want to get the first TrackEdit. It starts at time zero, so you can pass in time=0 and nextTimeEdgeOK, and you will get back 0 in interestingTime and the duration of the TrackEdit in interestingDuration. nextTimeIgnoreActiveSegment - if this flag is set, you can get times outside of the Active Segment. If you go off either end of the movie/track/media, the interestingTime returned is == -1 and the duration is meaningless. GetMediaNextInterestingTime ignores the nextTimeTrackEdit and nextTimeIgnoreActiveSegment flags. TRACK ALTERNATES The usage of alternate groups has been reworked. Instead of alternate groups being of a particular type (i.e. language or quality), they are just a big group of movies. Language is always the most important critera when the toolbox selects which track to enable from the group. Reselection of the active track in each alternate group occurs when the following calls are made: SetMovieLanguage, UpdateMovie, SetMovieGWorld, SetMovieBox, or the new SelectMovieAlternates. The reselection process examines each track in the alternate group and chooses the best one. The last movie language set is used to choose the language. If multiple tracks exist with the same language, media quality is examined. From there, media quality is examined. The low 6 bits of media quality are a bit map. Each bit corresponds to a bit depth. If a bit is set, it means that the media is “good” to use at that depth. Multiple bit depths can be set for a single track. After choosing the language of the alternate group, the toolbox attempts to choose a track whose bit depth best matches the depth it is being displayed into. The low six media quality bits are always bit depth flags. This is even true for sound tracks, which is somewhat bizarre but does allow you to tie video and sound tracks together across bit depth selections. If you set none of the bit depth flags, it means that the track will be selected if no track for the specific bit depth is available (esentially it makes the track the “default”). The next two bits up are defined to be a "quality level" -- 0 being worst and 3 being the best. If two or more tracks could be selected from a given alternate group (i..e their languages are the same, and they are both valid at the current bit depth), then we choose the track of the highest quality that will play back well. To do this, we call the media handler of each track and ask it how well it can play back the track on the current machine. We then choose the track of the highest available quality that will playback with the best performance. To make all this work for choosing between a 16 bit and an 8 bit sound track, you could set the quality for the 16 bit track to 0x0040 and to 0x0000 for the 8 bit track. On a machine that only supports 8 bit output, the sound media handler will only be able to play back half of the 16 bit data, so it chooses the 8 bit track. On a machine that supported 16 bit audio output (speculation left to the reader), the sound media handler would be able to play back all of the 16 bit or 8 bit data, but since the 16 bit track was marked as being of higher quality, the 16 bit track would be selected. There are two calls for alternate group support. SetAutoTrackAlternatesEnabled allows you to turn off the automatic reselection of alternate tracks that occurs in certain toolbox calls. A reselection is done when you enable auto-alternates with SetAutoTrackAlternatesEnabled. Currently these calls are UpdateMovie, SetMovieGWorld, and SetMovieBox. If the bit-depth did not change, these calls will perform a reselection. This list of calls may change in the future. The default is for auto track alternate selection to be on (true). If you wish to select alternate tracks using your own criteria, you may want to disable this features. SelectMovieAlternates makes the movie toolbox perform its alternate track enabling algorthim on the given movie. If automatic alternate selection is enabled, you should never need to call SelectMovieAlternates. If you disable auto alternates for a movie, you most likely want to open it in this state. To do this, use the newMovieDontAutoAlternate flag when you instantiate a movie. (see the NewMovie… calls) SetMovieLanguage performs a track reselection. If auto alternates are disabled, only those alternate groups which contain a track matching the language are effected. If no tracks of an alternate group are enabled, no tracks of the group will be enabled by an alternate track reselection operation. ---------- ADDED: pascal void SelectMovieAlternates(Movie m) ADDED: pascal void EnableAutoTrackAlternates(Movie m, Boolean enable) ---------- GONE: pascal void SetMovieQuality( Movie m, short quality ) ---------- CALLS WHICH CHANGED Added a new constant to the QTCallBackFlags. "triggerRateChange" allows you to specify that a rate change callback should fire on any rate change. The following calls interfaces' changed in response to testing requests. They also now return a reasonable creatorName. pascal void GetMediaHandlerDescription( Media m, OSType *mediaType, Str255 creatorName, OSType *creatorManufacturer ); pascal void GetMediaDataHandlerDescription( Media m, OSType *type, Str255 creatorName, OSType *creatorManufacturer ); M A T R I X R O U T I N E S The matrix routines went through a major overhaul. The calls that anyone were likely to use did not change (SetMatrixIdentity, TranslateMatrix, ScaleMatrix). ---------- OLD: pascal void ConcatMatrix( MatrixRecord *outP, MatrixRecord *bP, MatrixRecord *aP ); ------------------ NEW: pascal void ConcatMatrix( MatrixRecord *a, MatrixRecord *b); ---------- OLD: pascal Boolean InvertMatrix( MatrixRecord *mp ); NEW: pascal Boolean InverseMatrix( MatrixRecord *m, MatrixRecord *im ); ^^^^^^^^^^^^^^^^ ---------- OLD: pascal void TransformFixedPoints(MatrixRecord *m, short count, FixedPoint *fpt); NEW: pascal OSErr TransformFixedPoints(MatrixRecord *m, FixedPoint *fpt, long count); ^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^ ---------- OLD: pascal void TransformPoints( MatrixRecord *mp, short count, Point *pt1 ); NEW: pascal OSErr TransformPoints( MatrixRecord *mp, Point *pt1, long count ); ^^^^^ ^^^^^^^^^^ ^^^^^^^^^^ ---------- OLD: pascal Boolean TransformRect( MatrixRecord *m, Rect *r ); NEW: pascal Boolean TransformRect( MatrixRecord *m, Rect *r, FixedPoint *fpp); ^^^^^^^^^^^^^^^ ---------- OLD: pascal void TransformRgn( MatrixRecord *mp, RgnHandle r ); NEW: pascal OSErr TransformRgn( MatrixRecord *mp, RgnHandle r ); ^^^^^ ---------- - The usage of ConcatMatrix is: Multiply matrix A with matrix B and return result in B (B = B * A). (This is not a commutative operation.) - InvertMatrix is now InverseMatrix which takes two matrices instead of one and returns a boolean indicating whether or not an inverse was found. - TransformFixedPoints and TransformPoints now returns an OSErr and takes a long for the point count, and the parameter ordering changed - TransformRect takes an additional parameter which is a pointer to four 'FixedPoint's. If the pointer is nil, no points are returned. If the matrix is less than linear (only scale & translate), true is returned. Otherwise, the rect returned is the bounding box of the transformed rect and the points of the rect are returned in fpp. - TransformRgn now returns an OSErr. ---------- ADDED: pascal short GetMatrixType(MatrixRecord *m); ADDED: pascal void CopyMatrix(MatrixRecord *m1, MatrixRecord *m2); ADDED: pascal Boolean EqualMatrix(MatrixRecord *m1, MatrixRecord *m2); ADDED: pascal void SkewMatrix(MatrixRecord *m, Fixed skewX, Fixed skewY, Fixed aboutX, Fixed aboutY); ADDED: pascal Boolean TransformFixedRect(MatrixRecord *m, FixedRect *fr, FixedPoint *fpp); ADDED: pascal void AlignMatrix(register MatrixRecord *mrp, Rect *srcRect); ---------- - Given a matrix pointer GetMatrixType returns a number indicating the complexity of the matrix. [identity, translate, scale, linear (general 2x2), perspective (general 3x3)] - CopyMatrix and EqualMatrix were added. They are simple matrix utility routines. - SkewMatrix was added. It's along the same lines as ScaleMatrix, RotateMatrix, etc. - TransformFixedRect transforms a FixedRect. If the matrix is less than linear (only scale & translate), true is returned. Otherwise, the rect returned is the bounding box of the transformed rect and the points of the rect are returned in fpp. If you don't want the points, pass nil for fpp. - AlignMatrix adjusts the matrix so that the top-left of the srcRect is the same after transforming the srcRect through the matrix. ---------- GONE: psacal void GetMatrixTranslate( MatrixRecord *m, Fixed *deltaH, Fixed *deltaV ); GONE: pascal void GetMatrixScale( MatrixRecord *m, Fixed *hscale, Fixed *vscale ); GONE: pascal void ScaleMatrixTo( MatrixRecord *m, Fixed scaleX, Fixed scaleY ); GONE: pascal void TransformPoint( MatrixRecord *mp, short *y, short *x ); GONE: pascal void TransformMatrix( MatrixRecord *inouP, MatrixRecord *aP ); GONE: pascal Boolean GetMatrixRect( MatrixRecord *matrix, Rect *dstRect ); ---------- The above routines are gone. - GetMatrixTranslate and GetMatrixScale were never full implementations. - ScaleMatrixTo was not a general routine - You can use TransformPoints instead of TransformPoint I M A G E C O M P R E S S I O N The biggest changes to image compression involve parameters changing from unsigned longs to longs and all callout procs now take refcons. This impacts you in two ways, depending on the level of typechecking you employ, you will have to redeclare variables as long instead of unsigned long (the compiler will tell you all about it). The addition of refcons to the callout procs only affect you if are using callout procs. Instead of a proc ptr, the routines now take a pointer to a proc record. The proc record contains the proc ptr and the refcon. Since the refcon is not a parameter, if you used to pass nil for the proc ptr, you still pass nil for the proc record ptr. unsigned long ==> long DataProcPtr ==> DataProcRecordPtr typedef pascal OSErr (*DataProcPtr)(Ptr *dataP,long bytesNeeded,long refcon); ^^^^^^^^^^^ FlushProcPtr ==> FlushProcRecordPtr typedef pascal OSErr (*FlushProcPtr)(Ptr data,long bytesAdded,long refcon); ^^^^^^^^^^^ CompletionProcPtr ==> CompletionProcRecordPtr typedef pascal void (*CompletionProcPtr)(OSErr result,short flags,long refcon); ^^^^^^^^^^^ ProgressProcPtr ==> ProgressProcRecordPtr typedef pascal OSErr (*ProgressProcPtr)(short message,Fixed completeness,long refcon); ^^^^^^^^^^^ The resvd3 field in ImageDescription now contains frameCount. ---------- OLD: SetDSequenceTransferMode(ImageSequence seqID,short mode) NEW: SetDSequenceTransferMode(ImageSequence seqID,short mode,RGBColor *opColor) ^^^^^^^^^^^^^^^^^ ---------- OLD: GetSimilarity(PixMapHandle src,Rect *srcRect,ImageDescriptionHandle desc,Ptr data, unsigned char *similarity) NEW: GetSimilarity(PixMapHandle src,Rect *srcRect,ImageDescriptionHandle desc,Ptr data, Fixed *similarity) ^^^^^ ---------- OLD: GetImageDescriptionExtension(ImageDescriptionHandle desc,Handle *extension) NEW: GetImageDescriptionExtension(ImageDescriptionHandle desc,Handle *extension, long type,long index) ^^^^^^^^^ ^^^^^^^^^^ ---------- OLD: SetImageDescriptionExtension(ImageDescriptionHandle desc,Ptr extension, long size) --------- NEW: SetImageDescriptionExtension(ImageDescriptionHandle desc,Handle extension, long type) ^^^^^^ ^^^^^^^^^ ---------- OLD: GetCompressionSize(PixMapHandle src,Rect *srcRect, short colorDepth,CodecQ quality, CodecType cType,CompressorComponent codec,unsigned long *size) -------- NEW: GetMaxCompressionSize(PixMapHandle src,Rect *srcRect, short colorDepth,CodecQ quality, ^^^ CodecType cType,CompressorComponent codec,long *size) ---------- ADDED: pascal OSErr GetCompressedPixMapInfo(PixMapPtr pix,ImageDescriptionHandle *desc, Ptr *data,long *bufferSize, DataProcRecord *dataProc,ProgressProcRecord *progressProc) ADDED: pascal OSErr SetCompressedPixMapInfo(PixMapPtr pix,ImageDescriptionHandle desc, Ptr data,long bufferSize, DataProcRecordPtr dataProc,ProgressProcRecordPtr progressProc) ---------- SetDSequenceTransferMode now takes the opColor for the transfer mode. This is required to fully specify the transfer mode (opColor is required for arithmetic operations such as blend). GetImageDescription and SetImageDescription are routines which allow additional information to be attached to Image Descriptions. Get returns the nth extension. Each extension has a type so you know how to interpret it. GetCompressedPixMapInfo and SetCompressedPixMapInfo are utility routines for those of you using the new StdPix bottleneck for Pictures. J P E G C O D E C The version of the JPEG compressor from the alpha release had several significant defects. One was that the pixels values were not level shifted before encoding, resulting in strangely colored images. Another was a problem when generating certain high quality images, the compressed data was not in compliance with the standard. Both of these are corrected in the Beta version. Since the data created with the alpha version is not compatible with the new JPEG decompressor, the commpression type has been changed from 'JPEG' to 'jpeg'. There is a decompressor in the Beta release which can decode the alpha version of JPEG data, but this will not be supported in future releases. Any images created with the alpha version of the JPEG compressor should be recreated from the originals, or if that is not possible, by recompressing them from the alpha-compatibility JPEG decoder. Note that since these bugs were not fixed all at once, JPEG images created with releases of QuickTime between alpha nad beta may not decode correctly with either JPEG decompressor, but this only affects people who were seeded with those intermediate releases. I M A G E C O D E C The interface for implementing codecs changed dramatically. There were no conceptual changes to the way the codecs work, instead the changes involve the interface to the codecs. The change from unsigned long to long in Image Compression is carried through to the codec interface. Also the addition of refcons for all callout procs is also now apparent in the codec interface. Instead of pushing lots of parameters onto the stack for the PreCompress, BandCompress, PreDecompress, and BandDecompress, pointers to parameter blocks for these routines are passed. There is no longer a PostCompress or PostDecompress call. Instead there is a flag telling you that you are on the last band. If both first and last band bits are set, this will be the only call to BandDe/compress. Selectors were added to support codecGetCompressedPixMapInfo and codecSetCompressedPixMapInfo. The selector numbers for codecPreCompress, codecBandCompress, codecPreDecompress, and codecBandDecompress, changed. As mentioned above, the selectors for codecPostCompress and codecPostDecompress have gone away. Also, all the selectors for convert are gone. The capability flags changed in the following way: typedef struct { long flags; short wantedPixelSize; short extendWidth; short extendHeight; short bandMin; short bandInc; long time; ====> short pad; ====> unsigned long time; } CodecCapabilities; The CodecCapabilities struct now has a pad byte to long align the time field. The time field is now an unsigned value. The parameter block for the compress calls is: typedef struct { ImageSequence sequenceID; ImageDescriptionHandle imageDescription; Ptr data; long bufferSize; long frameNumber; long startLine; long stopLine; short conditionFlags; CodecFlags callerFlags; CodecCapabilities *capabilities; ProgressProcRecord progressProcRecord; CompletionProcRecord completionProcRecord; FlushProcRecord flushProcRecord; PixMap srcPixMap; PixMap prevPixMap; CodecQ spatialQuality; CodecQ temporalQuality; Fixed similarity; long reserved[2]; } CodecCompressParams; ---------- OlD: pascal ComponentResult CDBandCompress(ImageSequence seqID, ------------------- ImageDescriptionHandle desc,Ptr data,unsigned long *dataSize, --------------------------- -------- ----------------------- FlushProcPtr flushProc,PixMapPtr src,PixMapPtr prev,CodecQ spatialQ, ---------------------- ------------- -------------- --------------- CodecQ temporalQ,sBoolean firstBandInFrame,long frameNum,short startLine, ---------------- ------------------------- ------------- --------------- short stopLine,CodecFlags flags,CompletionProcPtr asyncProc) -------------- ---------------- --------------------------- NEW: pascal ComponentResult CDBandCompress(CodecCompressParams *params) ^^^^^^^^^^^^^^^^^^^^^^^^^^^ ---------- OlD: pascal ComponentResult CDPreCompress(ImageSequence seqID,ImageDescriptionHandle desc, ------------------- --------------------------- short pixelSize,CodecCapabilities *capabilites) --------------- ------------------------------ NEW: pascal ComponentResult CDPreCompress(CodecCompressParams *params) ^^^^^^^^^^^^^^^^^^^^^^^^^^^ ---------- GONE: pascal ComponentResult CDPostCompress(PREAMBLE,ImageSequence seqID, ImageDescriptionHandle desc,unsigned char *similarity,long *totalSize) ---------- The parameter block for the decompress calls is: typedef struct { ImageSequence sequenceID; ImageDescriptionHandle imageDescription; Ptr data; long bufferSize; long frameNumber; long startLine; long stopLine; short conditionFlags; CodecFlags callerFlags; CodecCapabilities *capabilities; ProgressProcRecord progressProcRecord; CompletionProcRecord completionProcRecord; DataProcRecord dataProcRecord; CGrafPtr port; PixMap dstPixMap; BitMapPtr maskBits; PixMapPtr mattePixMap; Rect srcRect; MatrixRecord *matrix; CodecQ accuracy; short transferMode; long reserved[2]; } CodecDecompressParams; ---------- OLD: pascal pascal ComponentResult CDBandDecompress(ImageSequence seqID, ------------------- CGrafPtr port,ImageDescriptionHandle desc,Ptr *data,unsigned long dataSize, ------------- --------------------------- --------- ---------------------- DataProcPtr dataProc, Rect *srcRect,short mode,CodecQ accuracy,PixMapPtr dst, -------------------- ------------- ---------- --------------- ------------- MatrixRecordPtr matrix,BitMap *maskBits,PixMapPtr matte, sBoolean firstBandInFrame, ---------------------- ---------------- --------------- ------------------------- long frameNum,short startLine,short stopLine,Boolean *changedMask,CodecFlags flags, ------------- --------------- -------------- -------------------- ---------------- CompletionProcPtr asyncProc) --------------------------- NEW: pascal ComponentResult CDPreDecompress(CodecDecompressParams *params) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ---------- OLD: pascal ComponentResult CDPreDecompress(ImageSequence seqID, ------------------- CGrafPtr port,ImageDescriptionHandle desc, Rect *srcRect,PixMapPtr dst, ------------- --------------------------- ------------- ------------- MatrixRecordPtr matrix,short mode, CodecQ accuracy, ---------------------- ---------- --------------- CodecCapabilities *capabilities) ------------------------------- NEW: pascal ComponentResult CDBandDecompress(CodecDecompressParams *params) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ---------- OLD: pascal ComponentResult CDGetCompressionSize(PixMapHandle src, Rect *srcRect, short depth, CodecQ quality, unsigned long *size) -------- NEW: pascal ComponentResult CDGetMaxCompressionSize(PixMapHandle src, Rect *srcRect, ^^^ short depth, CodecQ quality, long *size) ---------- OLD: pascal ComponentResult CDGetSimilarity(PixMapHandle src, Rect *srcRect, ImageDescriptionHandle desc, Ptr data, unsigned char *similarity) ------------- NEW: pascal ComponentResult CDGetSimilarity(PixMapHandle src, Rect *srcRect, ImageDescriptionHandle desc, Ptr data, Fixed *similarity) ^^^^^ ---------- GONE: pascal ComponentResult CDPostDecompress(PREAMBLE,ImageSequence seqID, ImageDescriptionHandle desc) ---------- The utility routines to assist Think C users in calling the proc ptrs are gone. Think C version 5 solves this problem. ---------- GONE: pascal OSErr CallDataProc(Ptr *p,long size,DataProcPtr proc) GONE: pascal OSErr CallFlushProc(Ptr p,long size,FlushProcPtr proc) GONE: pascal OSErr CallProgressProc(unsigned char progress,ProgressProcPtr proc) GONE: pascal void CallCompletionProc(OSErr result,CompletionProcPtr proc) ---------- C O M P O N E N T M A N A G E R The DelegateComponent call cannot accept a Component Reference. DelegateComponent must be called with a Component Instance. Added the following convenience call. ---------- NEW: pascal ComponentInstance OpenDefaultComponent( long componentType, long componentSubType ); ---------- This call finds and opens the first component of the Type,SubType specified. If the first one found fails to open then it keeps looking until it finds one that will open or it runs out of things to open. ---------- PREVIEW COMPONENTS Thumbnails.c and Thumbnails.h are now obsolete. Instead, preview information should be created/added to files using the PICT Preview Component or the Movie Preview Componnent. You may also define your own type of preview component to add custom previews to documents and to show those previews in Standard File. See PreviewComponent.h. ---------- Previewing in StandardFile Preview-capable versions of StandardGetFile and CustomGetFile have been defined: they are called StandardGetFilePreview and CustomGetFilePreview. Custom... may only be used under System 7.0, whereas StandardGetFilePreview may be used under either system 6 or system 7. The routines make use of any registered preview components to show previews for files. Both routines are identical to their namesakes except that the dialog box used for them must contain five additional standard dialog items. See StandardPreview.h. ---------- M O V I E C O N T R O L L E R 22 August 1991 29 August 1991 GONE: The following mcActions have been removed: mcStop, mcPlayBackwards, mcSetRate, mcIncreaseRate, mcDecreaseRate use mcPlay instead mcStepForward, mcStepBackward use mcStep instead mcToggleLooping use mcGetLooping and mcSetLooping mcIncreaseVolume, mcDecreaseVolume use mcGetVolume and mcSetVolume mcSetSelectionBegin, mcSetSelectionEnd changed to mcSetSelectionBegin and mcSetSelectionDuration, with the behaviour that mcSetSelectionBegin does nothing, just saves the time passed, and mcSetSelectionDuration then applies the beginning and the duration to the movie. Also, the duration can be negative. ADDED: New Actions: mcSetUseBadge and mcGetUseBadge - which take, for the parameter, a Boolean and a pointer-to-Boolean, respectively, to enable the use of badges to play the movie. The badge appears whenever the movie is stopped, the controller visible, and badges enabled. New Actions mcSetFlags and mcGetFlags - which take, as a parameter, a long of bits, or a pointer to a long of bits, respectively. The following bits are defined: typedef enum { mcFlagSuppressMovieFrame = 1<<0, Don't frame movie with a single pixel border mcFlagSuppressStepButtons = 1<<1, Don't draw the left/right step buttons mcFlagSuppressSpeakerButton = 1<<2 Don't draw the speaker-mute button } mcFlags; To change a single flag, you must get the flags long, alter it, and set the flags. CHANGED: MCShowHide -> MCSetVisible (name change only) MCIsShowing -> MCGetVisible (name change only) The MovieController is no longer defined to support multiple movies; the following calls are affected: MCAddMovie -> MCSetMovie, where setting movie “nil” removes a movie from the controller. MCRemoveMovie goes away. MCGetIndMovie -> MCGetMovie, and takes only the single MovieController parameter; no index. MCRemoveAllMovies goes away. MCGetControllerBoundsRect and MCGetControllerBoundsRgn are redefined to return the areas of the controller, and the movie, if one is set to the controller and attached. Similarly, MCSetControllerBoundsRect will resize the movie and the controller, if there is a movie and it is attached.